Program Annotations Endpoint
The Program Annotations endpoint supports the Program Video Descriptors feature. Typically, most programs are annotated with 20-30 video descriptors, but this can vary depending on the content. For example, a documentary movie may be lightly tagged compared to a live-action franchise movie based on a comic book. Within each Video Descriptor type, there can be anywhere from 1-5 video descriptors each. Specifically for Series, tagging is done at a show level covering over-arching descriptors across seasons and episodes.
For certain genres of programs, some types may not be relevant. In such cases, video descriptors from that type will not be present. See Video Descriptor Coverage
Each Program, identified by its TmsId, is annotated with Video Descriptors. The Program Annotations API provides the ID of the video descriptor. For each program object, Video Descriptors are grouped by video descriptor type. Within each video descriptor type, the video descriptors are sorted by descending order of importance. That is, the most important video descriptor for a given type appears first with ordinal number 1, followed by the next important video descriptor with ordinal number 2, and so on.
API and Example Responses
API
http://on-api.gracenote.com/v3/ProgramAnnotations
?updateId=[updateId value] &limit=[limit value] &api_key=[your-api-key]
Request Parameters
Important: Use lookup calls for QA and troubleshooting purposes only. Gracenote does not support lookup APIs for Client production environments.
Example Requests
Return full program annotation set in batches of 1000 programs.
http://on-api.gracenote.com/v3/ProgramAnnotations?updateId=0&limit=1000&api_key=<your-api-key>
Return Program Annotations data for set of TMSIds.
http://on-api.gracenote.com/v3/ProgramAnnotations?tmsId=MV010087880000,MV010021180981&api_key=123456789
Example Responses
See Program Annotation XML examples
Identifying a Deleted Program Annotation
When a Program Annotation contains "deleted=true", it indicates that this annotation is no longer valid and can be deleted from your databases. For more information see Removals (Object Deletion / Inactivation)
Data Structure and Relationships
Schema
Review the following XML schema definition (xsd) to learn about the data structure, fields, and types for this endpoint.
To explore the relationships among all endpoints, see the interactive schema documentation.
XML Schema URL
http://files.api.gracenote.com/xsd/on_update_programAnnotations_3.22.xsd
Unless stated otherwise, the XPATH in the tables below is relative to: on/programAnnotations/programAnnotation
| XPATH Element/Attribute | Description | Example |
|---|---|---|
| @TMSId | Program TMSId, used as primary identifier for the Program Annotations record | MV009352300000 |
| @rootId | Program root identifier | 13316368 |
| videoDescriptors/videoDescriptor/videoDescriptorId | Video descriptor identifier | GN1VBY6K9D0DWD4, GN0WQZ0H2MR816W |
| videoDescriptors/videoDescriptor/videoDescriptorId/weight | Weight assigned to a video descriptor | 9,7,5 |
The order of descriptor assignments to the program is arbitrary and does not imply importance.
Program Annotations Entity Relationship Diagram
The ProgramAnnotations endpoint works in conjunction with the Programs endpoint and VideoDescriptorsTaxonomy endpoint.
